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20. Objects, Message Passing, and Flavors 

The object-oriented programming style used in the Smalltalk and Actor families of languages 
is available in Zetalisp and used by the Lisp Machine software system. Its purpose is to perform 
generic operations on objects. Part of its implementation is simpiy a convention in procedure- 
calling style; part is a powerful language feature, called Flavors, for defining abstract objects. 
This chapter attempts 10 explain what programming with objects and with message passing means, 
the various means of implementing these in Zetalisp, and when you should use them. It assumes 
no prior knowledge of any other languages. 

20.1 Objects 

When writing a program, it is often convenient to model what the program does in terms of 
objects, conceptual entities that can be likened to real-world things. Choosing what objects to 
provide in a program is very important to the proper organization of the program. In an object- 
oriented design, specifying what objects exist is the first task in designing the system. In a text 
editor, the objects might be "pieces of text", "pointers into text", and "display windows". In an 
electrical design system, the objects might be "resistors", "capacitors", "transistors", "wires", and 
"display windows". After specifying what objects there are, the next task of the design is to 
figure out what operations can be performed on each object. In the text editor example, 
operations on "pieces of text" might include inserting text and deleting text; operations on 
"pointers into text" might include moving forward and backward; and operations on "display 
windows" might include redisplaying the window and changing which "piece of text" the window 
is associated with. 

In this model, we think of the program as being built around a set of objects, each of which 
has a set of operations that can be performed on it. More rigorously, the program defines several 
types of object (the editor above has three types), and it can create many instances of each type 
(that is, there can be many pieces of text, many pointers into text, and many windows). The 
program defines a set of types of object and, for each type, a set of operations that can be 
performed on any object of the type. 

This should not be wholly unfamiliar to the reader. Earlier in this manual, we saw a few 
examples of this kind of programming. A simple example is disembodied property lists, and the 
functions get, putprop, and remprop. The disembodied property list is a type of object; you 
can instantiate one with (cons nil nil) (that is, by evaluating this form you can create a new 
disembodied property list); there are three operations on the object, namely get, putprop, and 
remprop. Another example in the manual was the first example of the use of defstruct, which 
was called a ship, defstruct automatically defined some operations on this object, the operations 
to access its elements. We could define other functions that did useful things with ships, such as 
computing their speed, angle of travel, momentum, or velocity, stopping them, moving them 
elsewhere, and so on. 

In both cases, we represent our conceptual object by one Lisp object. The Lisp object we use 
for the representation has structure and refers to other Lisp objects. In the property list case, the 
Lisp object is a list with alternating indicators and values; in the ship case, the Lisp object is an 
array whose details are taken care of by defstruct. in both cases, we can say that the object 
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keeps track of an infernal slate, which can be examined and altered by the operations available 
for that type of object, get examines the suite of a property list, and putprop alters it; ship-x- 
position examines the state of a ship, and (setf (ship -mass) 5.0) alters it. 

We have now seen the essence of object-oriented programming. A conceptual object is 
modeled by a single Lisp object, which bundles up some state information. For every type of 
object, there is a set of operations that can be performed to examine or alter the state of the 
object. 

20.2 Modularity 

An important benefit of the object-oriented style is that it lends itself to a particularly simple 
and lucid kind of modularity. If you have modular programming constructs and techniques 
available, they help and encourage you to write programs that are easy to read and understand, 
and so arc more reliable and maintainable. Object-oriented programming lets a programmer 
implement a useful facility that presents the caller with a set of external interfaces, without 
requiring the caller to understand how the internal details of the implementation work. In other 
words, a program that calls this facility can treat the facility as a black box; the program knows 
what the facility's external interfaces guarantee to do, and that is all it knows. 

For example, a program that uses disembodied property lists never needs to know that the 
property list is being maintained as a list of alternating indicators and values; the program simply 
performs the operations, passing them inputs and getting back outputs. The program only 
depends on the external definition of these operations: it knows that if it putprops a property, 
and doesn't remprop it (or putprop over it), then it can do get and be sure of getting back the 
same thing it put in. The important thing about this hiding of the details of the implementation 
is that someone reading a program that uses disembodied property lists need not concern himself 
with how they are implemented; he need only understand what they undertake to do. This saves 
the programmer a lot of time and lets him concentrate his energies on understanding the program 
he is working on. Another good thing about this hiding is that the representation of property lists 
could be changed and the program would continue to work. For example, instead of a list of 
alternating elements, the property list could be implemented as an association list or a hash table. 
Nothing in the calling program would change at all. 

The same is true of the ship example. The caller is presented with a collection of operations, 
such as ship-x-position. ship-y-position, ship-speed, and ship-direction; it simply calls these 
and looks at their answers, without caring how they did what they did. In our example above, 
ship-x-position and ship-y-position would be accessor functions, defined automatically by 
defstruct, while ship -speed and ship -direction would be functions defined by the implementor 
of the ship type. The code might look like this: 
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(defstruct (ship) 
ship-x-posi tion 
ship-y-posi tion 
ship-x-veloci ty 
shi p-y-veloci ty 
ship-mass) 

(defun ship-speed (ship) 

(sqrt (+ (" (ship-x-velocity ship) 2) 

( A (ship-y-veloci ty ship) 2)))) 

(defun ship-direction (ship) 
(atan (ship-y-veloci ty ship) 

(ship-x-velocity ship))) 

The caller need not know that the first two functions were structure acccssors and that the 
second two were written by hand and do arithmetic. Those facts would not be considered part of 
the black box characteristics of the implementation of the ship type. The ship type does not 
guarantee which functions will be implemented in which ways; such aspects are not part of the 
contract between ship and its callers. In fact, ship could have been written this way instead: 

(defstruct (ship) 
ship-x-posi tion 
ship-y-posi tion 
ship-speed 
ship-direction 
ship-mass) 

(defun ship-x-velocity (ship) 

(* (ship-speed ship) (cos (ship-direction ship)))) 

(defun ship-y-veloci ty (ship) 

(* (ship-speed ship) (sin (ship-direction ship)))) 

In this second implementation of the ship type, we have decided to store the velocity in polar 
coordinates instead of rectangular coordinates. This is purely an implementation decision. The 
caller has no idea which of the two ways the implementation uses; he just performs the 
operations on the object by calling the appropriate functions. 

We have now created our own types of objects, whose implementations are hidden from the 
programs that use them. Such types are usually referred to as abstract types. The object-oriented 
style of programming can be used to create abstract types by hiding the implementation of the 
operations and simply documenting what the operations are defined to do. 

Some more terminology: the quantities being held by the elements of the ship structure are 
referred to as instance variables. Each instance of a type has the same operations defined on it; 
what distinguishes one instance from another (besides eqness) is the values that reside in its 
instance variables. The example above illustrates that a caller of operations docs not know what 
the instance variables are; our two ways of writing the ship operations have different instance 
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variables, but from the outside they have exactly die same operations. 

One might ask: "But what if the caller evaluates (aref ship 2) and notices that he gets back 
the x-vclocity rather than the speed? Then he can tell which of die two implementations were 
used." This is true; if the caller were to do that, he could tell. However, when a facility is 
implemented in the object-oriented style, only certain functions are documented and advertised, 
the functions that are considered to be operations on the type of object. The contract from ship 
to its callers only speaks about what happens if the caller calls these functions. The contract 
makes no guarantees at all about what would happen if the caller were to start poking around on 
his own. using aref. A caller who does so is in error; he is depending on something that is not 
specified in the contract. No guarantees were ever made about the results of such action, and so 
anything may happen; indeed, ship may get rcimplemented overnight, and the code that does the 
aref will have a different effect entirely and probably stop working. This example shows why the 
concept of a contract between a callee and a caller is important: the contract specifies the 
interface between the two modules. 

Unlike some other languages that provide abstract types, Zctalisp makes no attempt to have 
the language automatically forbid constructs that circumvent the contract. ITiis is intentional. One 
reason for this is that the Lisp Machine is an interactive system, and so it is important to be able 
to examine and alter internal state interactively (usually from a debugger). Furthermore, mere is 
no strong distinction between the "system" programs and die "user" programs on the Lisp 
Machine; users are allowed to get into any part of the language system and change what they 
want to change. 

In summary: by defining a set of operations and making only a specific set of external 
entrypoints available to the caller, the programmer can create his own abstract types. These types 
can be useful facilities for other programs and programmers. Since the implementation of the 
type is hidden from the callers, modularity is maintained and the implementation can be changed 
easily. 

We have hidden the implementation of an abstract type by making its operations into 
functions which the user may call. The important thing is not that they are functions— in Lisp 
everything is done with functions. The important thing is that we have defined a new conceptual 
operation and given it a name, rather than requiring anyone who wants to do the operation to 
write it out step-by-stcp. Thus we say (ship-x-velocity s) rather than (aref s 2). 

It is just as true of such abstract-operation functions as of ordinary functions that sometimes 
they are simple enough that we want the compiler to compile special code for them rather than 
really calling the function. (Compiling special code like this is often called open-coding.) The 
compiler is directed to do this through use of macros, defsubsts, or optimizers, defstruct 
arranges for this kind of special compilation for the functions that get the instance variables of a 
structure. 

When we use this optimization, the implementation of the abstract type is only hidden in a 
certain sense. It does not appear in the Lisp code written by the user, but does appear in the 
compiled code. ITie reason is that there may be some compiled functions that use the macros (or 
whatever); even if you change the definition of the macro, the existing compiled code will 
continue to use the old definition. Thus, if the implementation of a module is changed programs 
that use it may need to be recompiled. This is something we sometimes accept for the sake of 
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In the present implementation of flavors, which is discussed below, there is no such compiler 
incorporation of nonmodular knowledge into a program, except when the :ordered- instance - 
variables feature is used; see page 346, where this problem is explained further. If you don't 
use the :ordered- instance -variables" feature, you don't have to worry about this. 

20.3 Generic Operations 

Suppose we think about the rest of the program that uses the ship abstraction. It may want 
to deal with other objects that are like ships in that they are movable objects with mass, but 
unlike ships in other ways. A more advanced model of a ship might include the concept of the 
ship's engine power, the number of passengers on board, and its name. An object representing a 
meteor probably would not have any of these, but might have another attribute such as how 
much iron is in it. 

However, all kinds of movable objects have positions, velocities, and masses, and the system 
will contain some programs that deal with these quantities in a uniform way, regardless of what 
kind of object the attributes apply to. For example, a piece of the system that calculates every 
object's orbit in space need not worry about the other, more peripheral attributes of various types 
of objects; it works the same way for all objects. Unfortunately, a program that tries to calculate 
the orbit of a ship will need to know the ship's attributes, and will have to call ship-x-position 
and ship-y-velocity and so on. The problem is that these functions won't work for meteors. 
There would have to be a second program to calculate orbits for meteors that would be exactly 
the same, except that where the first one calls ship-x-position, the second one would call 
meteor-x- position, and so on. This would be very bad; a great deal of code would have to 
exist in multiple copies, all of it would have to be maintained in parallel, and it would take up 
space for no good reason. 

What is needed is an operation that can be performed on objects of several different types. 
For each type, it should do the thing appropriate for that type. Such operations are called 
generic operations. The classic example of generic operations is the arithmetic functions in most 
programming languages, including Zetalisp. The + (or plus) function will accept either fixnums 
or flonums, and perform either fixnum addition or flonum addition, whichever is appropriate, 
based on the data types of the objects being manipulated. In our example, we need a generic x- 
position operation that can be performed on either ships, meteors, or any other kind of mobile 
object represented in the system. TTiis way, we can write a single program to calculate orbits. 
When it wants to know the x position of the object it is dealing with, it simply invokes the 
generic x- position operation on the object, and whatever type of object it has, the correct 
operation is performed, and the x position is returned. 

Another terminology for the use of such generic operations has emerged from the Smalltalk 
and Actor languages: performing a generic operation is called sending a message. The message 
consists of an operation name (a symbol) and arguments. The objects in the program are thought 
of as little people, who get sent messages and respond with answers (returned values). In the 
example above, the objects are sent x- position messages, to which they respond with their x 
position. 
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Sending a message is a way of invoking a function without specifying which function is to be 
called. Instead, the data determines the function to use. The caller specifics an operation name 
and an object; that is, it said what operation to perform, and what object to perform it on. The 
function to invoke is found from this information. 

The two data used to figure out which function to call arc the type of the object, and the 
name of the operation. The same set of functions arc used for all instances of a given type, so 
the type is the only attribute of the object used to figure out which function to call. The rest of 
the message besides the operation are data which are passed as arguments to the function, so the 
operation is the only part of the message used to find the function. Such a function is called a 
method. For example, if we send an x- position message to an object of type ship, then the 
function we find is "the ship type's x- position method". A method is a function that handles a 
specific operation on a specific kind of object; this method handles messages named x- position to 
objects of type ship. 

In our new terminology: the orbit-calculating program finds the x position of the object it is 
working on by sending that object a message consisting of the operation x- position and no 
arguments. The returned value of the message is the x position of the object. If the object was 
of type ship, then the ship type"s x- position method was invoked; if it was of type meteor, 
then the meteor type's x -position method was invoked. The orbit-calculating program just sends 
the message, and the right function is invoked based on the type of the object. We now have 
true generic functions, in the form of message passing: the same operation can mean different 
things depending on the type of the object. 

20.4 Generic Operations in Lisp 

How do we implement message passing in Lisp? Our convention is that objects that receive 
messages are always functional objects (that is, you can apply them to arguments). A message is 
sent to an object by calling that object as a function, passing the operation name as the first 
argument and the arguments of the message as the rest of the arguments. Operation names are 
represented by symbols; normally these symbols are in the keyword package (see chapter 24, page 
506), since messages are a protocol for communication between different programs, which may 
reside in different packages. So if we have a variable my-ship whose value is an object of type 
ship, and we want to know its x position, we send it a message as follows: 

(funcall my-ship * :x-position) 

This form returns the x position as its returned value. To set the ship's x position to 3.0, we 
send it a message like this: 

(funcall my-ship ' :set-x-position 3.0) 

It should be stressed that no new features are added to Lisp for message sending; we simply 
define a convention on the way objects take arguments. The convention says that an object 
accepts messages by always interpreting its first argument as an operation name. The object must 
consider this operation name, find the function which is the method for that operation, and 
invoke that function. 
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This raises the question of how message receiving works. The object must somehow find the 
right method for the message it is sent. Furthermore, the object now has to be callable as a 
function; objects can't just be defstructs any more, since those aren't functions. But the structure 
defined by defstruct was doing something useful: it was holding the instance variables (the 
internal state) of the object. We need a function with internal state; that is, we need a coroutine. 

Of the Zetalisp features presented so far, the most appropriate is the closure (see chapter 11, 
page 180). A message-receiving object could be implemented as a closure over a set of instance 
variables. The function inside the closure would have a big selectq form to dispatch on its first 
argument. (Actually, rather than using closures and a selectq, you would probably use entities 
and defselect; see section 11.4, page 185.) 

While using closures (or entities) does work, it has several serious problems. The main 
problem is that in order to add a new operation to a system, it is necessary to modify a lot of 
code; you have to find all the types that understand that operation, and add a new clause to the 
selectq. The problem with this is that you cannot textually separate the implementation of your 
new operation from the rest of the system; the methods must be interleaved with the other 
operations for the type. Adding a new operation should only require adding Lisp code; it should 
not require modifying Lisp code. 

The conventional way of making generic operations is to have a procedure for each operation, 
which has a big selectq for all the types; this means you have to modify code to add a type. 
The way described above is to have a procedure for each type, which has a big selectq for all 
the operations; this means you have to modify code to add an operation. Neither of these has 
the desired property that extending the system should onlv require adding code, rather than 
modifying code. 

Closures (and entities) are also somewhat clumsy and crude. A far more streamlined, 
convenient, and powerful system for creating message- receiving objects exists; it is called the 
flavor mechanism. With flavors, you can add a new method simply by adding code, without 
modifying anything. Furthermore, many common and useful things are very easy to do with 
flavors. The rest of this chapter describes flavors. 

20.5 Simple Use of Flavors 

A flavor, in its simplest form, is a definition of an abstract type. New flavors are created 
with the defflavor special form, and methods of the flavor are created with the defmethod special 
form. New instances of a flavor are created with the make- instance function. This section 
explains simple uses of these forms. 

For an example of a simple use of flavors, here is how the ship example above would be 
implemented. 
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(defflavor ship (x-position y-position 

x-velocity y-velocity mass) 


:gett able- instance- variables) 

(defmethod (ship :speed) {) 
(sqrt (+ (~ x-velocity 2) 

(~ y-velocity 2)))) 

(defmethod (ship :direction) () 
(atan y-velocity x-velocity)) 

The code above creates a new flavor. The first subform of the defflavor is ship, which is the 
name of the new flavor. Next is the list of instance variables; they are the five that should be 
familiar by now. The next subform is something we will get to later. The rest of the subforms 
are the body of the defflavor, and each one specifies an option about this flavor. In our 
example, there is only one option, namely :gettable- instance -variables. This means that for 
each instance variable, a method should automatically be generated to return the value of that 
instance variable. The name of the operation is a symbol with the same name as the instance 
variable, but interned on the keyword package. Thus, methods are created to handle the 
operations :x- position, :y- position, and so on. 

Each of the two defmethod forms adds a method to the flavor. The first one adds a handler 
to the flavor ship for the operation :speed. The second subform is the lambda-list, and the rest 
is the body of the function that handles the :speed operation. The body can refer to or set any 
instance variables of the flavor, the same as it can with local variables or special variables. When 
any instance of the ship flavor is invoked with a first argument of :direction, the body of the 
second defmethod will be evaluated in an environment in which the instance variables of ship 
refer to the instance variables of this instance (the one to which the message was sent). So when 
the arguments of atan are evaluated, the values of instance variables of the object to which the 
message was sent will be used as the arguments, atan will be invoked, and the result it returns 
will be returned by the instance itself. 

Now we have seen how to create a new abstract type: a new flavor. Every instance of this 
flavor will have the five instance variables named in the defflavor form, and the seven methods 
we have seen (five that were automatically generated because of the :gettable- instance -variables 
option, and two that we wrote ourselves). The way to create an instance of our new flavor is 
with the make-instance function. Here is how it could be used: 

(setq my-ship (make-instance 'ship)) 

This will return an object whose printed representation is: 

#<SHIP 13731210> 

(Of course, the value of the magic number will vary; it is not interesting anyway.) The 
argument to make -instance is, as you can see, the name of the flavor to be instantiated. 
Additional arguments, not used here, are mil options, that is, commands to the flavor of which 
we are making an instance, selecting optional features. This will be discussed more in a moment. 
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Examination of the flavor we have defined shows that it is quite useless as it stands, since 
there is no way to set any of the parameters. We can fix this up easily by putting the lettable - 
instance -variables option into the defflavor form. This option tells defflavor to generate 
methods for operations :set-x-position, :set-y- position, and so on; each such method takes one 
argument and scu> die cuncbpuncung inswiat vanauiv, iu mv giivw "Ji»v. 

Another option we can add to the defflavor is :inittable-instance- variables, which allows us 
to initialize the values of the instance variables when an instance is first created. :inittable- 
instance-variables docs not create any methods; instead, it makes initialization keywords named 
:x-position, :y- position, etc., that can be used as init-option arguments to make-instance to 
initialize the corresponding instance variables. The set of init options are sometimes called the 
init-plist because they arc like a property list. 

Here is the improved defflavor: 

(defflavor ship (x-position y-position 

x-velocity y-velocity mass) 


gett able-instance-variables 

sett able-instance-variables 

initt able-instance-variables) 

All we have to do is evaluate this new defflavor, and the existing flavor definition will be 
updated and now include the new methods and initialization options. In fact, the instance we 
generated a while ago will now be able to accept these new operations! We can set the mass of 
the ship we created by evaluating 

(funcall my-ship ':set-mass 3.0) 
and the mass instance variable of my-ship will properly get set to 3.0. If you want to play 
around with flavors, it is useful to know that describe of an instance tells you the flavor of the 
instance and the values of its instance variables. If we were to evaluate (describe my-ship) at 
this point, the following would be printed: 

#<SHIP 13731210>, an object of flavor SHIP, 
has instance variable values: 



X-POSITION 


unbound 


Y-POSITION 


unbound 


X-VELOCITY 


unbound 


Y-VELOCITY 


unbound 


MASS: 


3.0 



Now that the instance variables are "inittable", we can create another ship and initialize some 
of the instance variables using the init-plist. Let's do that and describe the result: 
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(setq her-ship (make-instance 'ship ':x-position 0.0 

' :y-position 2.0 
' :mass 3.5)) 
=> #<SHIP 13756521> 



(describe her-ship) 

#<SHIP 13756521>, an object of flavor SHIP, 
has instance variable values: 



X-POSITION 


0.0 


Y-POSITION 


2.0 


X-VELOCITY 


unbound 


Y-VELOCITY 


unbound 


MASS: 


3.5 



A flavor can also establish default initial values for instance variables. These default values are 
used when a new instance is created if the values are not initialized any other way. The syntax 
for specifying a default initial value is to replace the name of the instance variable by a list, 
whose first element is the name and whose second is a form to evaluate to produce the default 
initial value. For example: 

(defvar *default-x-velocity* 2.0) 
(defvar *def aul t-y-veloci ty* 3.0) 

(defflavor ship ((x-position 0.0) 

(y-position 0.0) 

(x- velocity *defaul t-x- velocity *) 

(y-velocity *defaul t-y- velocity *) 
mass) 


: get table- instance- variables 

:sett able-instance-variables 
:initt able-instance- variables) 

(setq another-ship (make-instance 'ship ':x-position 3.4)) 

(describe another-ship) 

#<SHIP 14563643>, an object of flavor SHIP, 
has instance variable values: 



X-POSITION 


3.4 


Y-POSITION 


0.0 


X-VELOCITY 


2.0 


Y-VELOCITY 


3.0 


MASS: 


unbound 



x-position was initialized explicitly, so the default was ignored, y-position was initialized 
from the default value, which was 0.0. The two velocity instance variables were initialized from 
their default values, which came from two global variables, mass was not explicitly initialized 
and did not have a default initialization, so it was left unbound. 
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There are many other options that can be used in def flavor, and the in it options can be used 
more flexibly than just to initialize instance variables; full details are given later in this chapter. 
But even with the small set of features we have seen so far, it is easy to write object-oriented 
programs. 

20.6 Mixing Flavors 

Now we have a system for defining message-receiving objects so that we can have generic 
operations. If we want to create a new type called meteor that would accept the same generic 
operations as ship, we could simply write another defflavor and two more defmethods that 
looked just like those of ship, and then meteors and ships would both accept the same 
operations, ship would have some more instance variables for holding attributes specific to ships 
and some more methods for operations that are not generic, but are only defined for ships; the 
same would be true of meteor. 

However, this would be a a wasteful thing to do. The same code has to be repeated in 
several places, and several instance variables have to be repeated. The code now needs to be 
maintained in many places, which is always undesirable. r rhe power of flavors (and the name 
"flavors") comes from the ability to mix several flavors and get a new flavor. Since the 
functionality of ship and meteor partially overlap, we can take the common functionality and 
move it into its own flavor, which might be called moving -object. We would define moving - 
object the same way as we defined ship in the previous section. Then, ship and meteor could 
be defined like this: 

(defflavor ship (engine-power number-of-passengers name) 
(moving-object) 
: get table- instance- variables) 

(defflavor meteor (percent-iron) (moving-object) 
: inittable- instance- variables) 

These defflavor forms use the second subform, which we ignored previously. The second 
subform is a list of flavors to be combined to form the new flavor; such flavors are called 
components. Concentrating on ship for a moment (analogous things are true of meteor), we see 
that it has exactly one component flavor: moving -object. It also has a list of instance variables, 
which includes only the ship-specific instance variables and not the ones that it shares with 
meteor. By incorporating moving -object, the ship flavor acquires all of its instance variables, 
and so need not name them again. It also acquires all of moving -object's methods, too. So 
with the new definition, ship instances will still implement the :x -velocity and :speed operations, 
and they will do the same thing. However, the :engine- power operation will also be understood 
(and will return the value of the engine -power instance variable). 

What we have done here is to take an abstract type, moving -object, and build two more 
specialized and powerful abstract types on top of it. Any ship or meteor can do anything a 
moving object can do, and each also has its own specific abilities. This kind of building can 
continue; we could define a flavor called ship -with -passenger that was built on top of ship, 
and it would inherit all of moving -object's instance variables and methods as well as ship's 
instance variables and methods. Furthermore, the second subform of defflavor can be a list of 
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several components, meaning that the new flavor should combine all the instance variables and 
methods of all the flavors in the list, as well as the ones those flavors arc built on, and so on. 
All the components taken together form a big tree of flavors. A flavor is built from its 
components, its components' components, and so on. We sometimes use the term "components" 
to mean the immediate components (the ones listed in the defflavor), and sometimes to mean all 
the components (including the components of the immediate components and so on). (Actually, it 
is not strictly a tree, since some flavors might be components through more than one path. It is 
really a directed graph; it can even be cyclic.) 

The order in which the components are combined to form a flavor is important. The tree of 
flavors is turned into an ordered list by performing a top-down, depth-first walk of the tree, 
including non-terminal nodes before the subtrees they head, ignoring any flavor that has been 
encountered previously somewhere else in the tree. For example, if flavor- 1's immediate 
components are flavor-2 and flavor-3, and flavor-2's components are fiavor-4 and flavor-5, 
and flavor-3's component was flavor-4, then the complete list of components of flavor-1 would 
be: 

flavor-1, flavor-2, flavor-4, flavor-5, flavor-3 
The flavors earlier in this list are the more specific, less basic ones; in our example, ship -with - 
passengers would be first in the list, followed by ship, followed by moving -object. A flavor is 
always the first in the list of its own components. Notice that flavor-4 does not appear twice in 
this list. Only the first occurrence of a flavor appears; duplicates arc removed. (The elimination 
of duplicates is done during the walk; if there is a cycle in the directed graph, it will not cause a 
non-terminating computation.) 

The set of instance variables for the new flavor is the union of all the sets of instance 
variables in all the component flavors. If both flavor-2 and flavor-3 have instance variables 
named foo, then flavor-1 will have an instance variable named foo, and any methods that refer 
to foo will refer to this same instance variable. Thus different components of a flavor can 
communicate with one another using shared instance variables. (Typically, only one component 
ever sets the variable, and the others only look at it.) The default initial value for an instance 
variable comes from the first component flavor to specify one. 

The way the methods of the components are combined is the heart of the flavor system. 
When a flavor is defined, a single function, called a combined method, is constructed for each 
operation supported by the flavor. This function is constructed out of all the methods for that 
operation from all the components of the flavor. There are many different ways that methods can 
be combined; these can be selected by the user when a flavor is defined. The user can also 
create new forms of combination. 

There are several kinds of methods, but so far, the only kinds of methods we have seen are 
primary methods. The default way primary methods are combined is that all but the earliest one 
provided are ignored. In other words, the combined method is simply the primary method of the 
first flavor to provide a primary method. What this means is that if you are starting with a flavor 
foo and building a flavor bar on top of it, then you can override foo's method for an operation 
by providing your own method. Your method will be called, and foo's will never be called. 

Simple overriding is often useful; if you want to make a new flavor bar that is just like foo 
except that it reacts completely differently to a few operations, then this will work. However, 
often you don't want to completely override the base flavor's (foo's) method; sometimes you want 
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to add some extra things to be done. This is where combination of methods is used. 

The usual way methods are combined is that one flavor provides a primary method, and other 
flavors provide daemon methods. The idea is that the primary method is "in charge" of the main 
business of handling the operation, but other flavors just want to keep informed that the message 
was sent, or just want to do the part of the operation associate^ with their own area o* 
responsibility. 

When methods are combined, a single primary method is found; it comes from the first 
component flavor that has one. Any primary methods belonging to later component flavors are 
ignored. This is just what we saw above; bar could override foo's primary method by providing 
its own primary method. 

However, you can define other kinds of methods; in particular, daemon methods. They come 
in two kinds, before and after. There is a special syntax in defmethod for defining such 
methods. Here is an example of the syntax. To give the ship flavor an after-daemon method for 
the :speed operation, the following syntax would be used: 
(defmethod (ship :after :speed) () 
body) 

Now, when a message is sent, it is handled by a new function called the combined method. 
The combined method first calls all of the before daemons, then the primary method, then all the 
after daemons. Each method is passed the same arguments that the combined method was given. 
The returned values from the combined method are the values returned by the primary method; 
an v values returned from the daemons. arc ignored. Before-daemons are called in the order that 
flavors are combined, while after-daemons are called in the reverse order. In other words, if you 
build bar on top of foo, then bar's before-daemons will run before any of those in foo, and 
bar's after-daemons will run after any of those in foo. 

The reason for this order is to keep the modularity order correct. If we create flavor- 1 built 
on flavor-2; then it should not matter what flavor-2 is built out of. Our new before-daemons 
go before all methods of flavor-2, and our new after-daemons go after all methods of flavor-2. 
Note that if you have no daemons, this reduces to the form of combination described above. The 
most recently added component flavor is the highest level of abstraction; you build a higher-level 
object on top of a lower-level object by adding new components to the front. The syntax for 
defining daemon methods can be found in the description of defmethod below. 

To make this a bit more clear, let's consider a simple example that is easy to play with: the 
:print-self method. The Lisp printer (i.e. the print function; see section 21.2.1, page 367) prints 
instances of flavors by sending them :print-self messages. The first argument to the :print-self 
operation is a stream (we can ignore the others for now), and the receiver of the message is 
supposed to print its printed representation on the stream. In the ship example above, the reason 
thaT instances'", of the ship flavor printed the way they did is because die ship flavor was actually 
built on top of a very basic flavor called vanilla-flavor; this component is provided automatically 
by defflavor. It was vanilla-flavor's :print-self method that was doing the printing. Now, if we 
give ship its own primary method for the :print-self operation, then that method will take over 
the job of printing completely; vanilla-flavor's method will not be called at all. However, if we 
give ship a before-daemon method for the :print-self operation, then it will get invoked before 
the vanilla-flavor method, and so whatever it prints will appear before what vanilla-flavor prints. 
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So we can use beforc-dacmons to add prefixes to a printed representation; similarly, after- 
daemons can add suffixes. 

ITiere are other ways to combine methods besides daemons, but this way is the most 
common. The more advanced ways of combining methods are explained in a later section; see 
section 20.11, page 350. The vanilla-flavor and what it does for you are also explained later'; see 
section 20.10, page 348. 

20.7 Flavor Functions 

defnavor Macro 

A flavor is defined by a form 

(defflavor flavor- name ( varl var2. . . ) (flavl flav2. . . ) 

opt I opt2. . . ) 

flavor-name is a symbol which serves to name this flavor. It will get an si:flavor property 

of the internal data-structure containing the details of the flavor. 

(typep obj), where obj is an instance of the flavor named flavor-name, will return the 
symbol flavor-name, (typep obj flavor-name) is t if obj is an instance of a flavor, one of 
whose components (possibly itself) is flavor-name. 

varl. var2, etc. are the names of the instance- variables containing the local state for this 
flavor. A list of the name of an instance- variable and a default initialization form is also 
acceptable; the initialization form will be evaluated when an instance of the flavor is 
created if no other initial value for the variable is obtained. If no initialization is 
specified, the variable will remain unbound. 

flavl, flav2, etc. are the names of the component flavors out of which this flavor is built. 
The features of those flavors are inherited as described previously. 

optl, op(2, etc. are options; each option may be either a keyword symbol or a list of a 
keyword symbol and arguments, rhe options to defflavor are described in section 20.8, 
page 342. 

•all -flavor-names* Variable 

This is a list of the names of all the flavors that have ever been defflavor'ed. 

defmethod Macw 

A method, that is, a function to handle a particular operation for instances of a particular 
flavor, is defined by a form such as 

(defmethod (flavor-name method- type operation) lambda-list 
forml form2. . . ) 
flavor-name is a symbol which is the name of the flavor which is to receive the method. 
operation is a keyword symbol which names the operation to be handled, method-type is a 
keyword symbol for the type of method: it is omitted when you are defining a primary 
method. For some method-types, additional information is expected. It comes after 
operation. 
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The meaning of the method- type depends on what kind of method-combination is declared 
for this operation. For instance, for daemons :before and :after are allowed. See section 
20.11, page 350 for a complete description of method types and the way methods are 
combined. 

lambda-list describes die arguments and &aux variables of the function; the first argument 
to die method, which is die operation name itself, is automatically handled and so is not 
included in die lambda-list. Note that methods may not have &quote arguments; that is 
they must be functions, not special forms, fonnl, form2, etc. are the function body; the 
value of the last form is returned. 

The variant form 

(defmethod (flavor- name operation) function) 
where function is a symbol, says that flavor- name's mediod for operation is function, a 
symbol which names a function. That function must take appropriate arguments; the first 
argument is the operation. 

If you redefine a method that is already defined, the old definition is replaced by the new 
one. Given a flavor, an operation name, and a method type, there can only be one 
function (with the exception of :case methods), so if you define a :before daemon 
method for die foo flavor to handle the :bar operation, then you replace the previous 
before-daemon; however, you do not affect the primary method or methods of any other 
type, operation or flavor. 

The function spec for a method (see section 10.2, page 155) looks like: 
( : me t h o d flavor- name operation ) or 
(: met hod flavor-name method- type operation) 
(: met hod flavor- name method- type operation suboperation) 

This is useful to know if you want to trace (page 588), breakon (page 591) or advise 

(page 593) a method, or if you want to poke around at the mediod function itself, e.g. 

disassemble it (see page 641). 

make- instance flavor-name init-optionl value! init-optionl value!... 

Creates and returns an instance of the specified flavor. Arguments after the first are 
alternating init-option keywords and arguments to those keywords. These options are used 
to initialize instance variables and to select arbitrary options, as described above. An :init 
message is sent to the newly-created object with one argument, the init-plist. This is a 
disembodied property-list containing the init-options specified and those defaulted from the 
flavor's :default-init-plist (however, init keywords diat simply initialize instance variables, 
and the corresponding values, may be absent when the :init methods are called), make- 
instance is an easy-to-call interface to instantiate -flavor; for full details refer to that 
function. 

instantiate-flavor flavor-name init-plist &optional send-init-message-p 
return- unhandled- keywords area 
This is an extended version of make -instance, giving you more features. Note that it 
takes the init-plist as an argument, rather than taking a &rest argument of init-options 
and values. 
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The inii-plisl argument must be a disembodied property list; locf of a &rest argument 
will do. Beware! This property list can be modified; the properties from the default-init- 
plist are putprop'cd on if not already present, and some :init methods do explicit 
putprops onto the init-plist. 

The :init methods should not look on the init-plist for keywords that simply initialize 
instance variables (that is, keywords defined with rinittable- instance -variables rather than 
:init-keywords). The corresponding instance variables will already be set up when the 
:init methods arc called, and sometimes the keywords and their values may actually be 
missing from the init-plist if it is more efficient not to put them on. To avoid problems, 
always refer to the instance variables themselves rather than looking for the init keywords 
that initialize them. 

In die event that :init methods remprop properties already on the init-plist (as opposed to 
simply doing get and putprop), then the init-plist will get rplacd'ed. This means that the 
actual list of options will be modified. It also means that locf of a &rest argument will 
not work; die caller of instantiate -flavor must copy its rest argument (e.g. with copylist); 
this is because rplacd is not allowed on &rest arguments. 

First, if the flavors method hash-table and other internal information have not been 
computed or are not up to date, they are computed, lliis may take a substantial amount 
of time and invoke the compiler, but will only happen once for a particular flavor no 
matter how many instances you make, unless you redefine the flavor. 

Next, the instance variables are initialized. There are several ways this initialization can 
happen. If an instance variable is declared inittable, and a keyword with the same 
spelling as its name appears in init-plist, it is set to the value specified after that keyword. 
If an instance variable does not get initialized this way, and an initialization form was 
specified for it in a defflavor, that form is evaluated and the variable is set to the result 
The initialization form may not refer to any instance variables or to self; it will not be 
evaluated in the "inside" environment in which methods are called. If an instance variable 
does not get initialized either of these ways it will be left unbound; an :init method may 
initialize it (see below). Note that a simple empty disembodied property list is (nil), 
which is what you should give if you want an empty init-plist. If you use nil, the 
property list of nil will be used, which is probably not what you want. 

If any keyword appears in the init-plist but is not used to initialize an instance variable 
and is not declared in an .init -keywords option (see page 343) it is presumed to be a 
misspelling. So any keywords that you handle in an :init handler should also be 
mentioned in the :init- keywords option of the definition of the flavor. 

If the return-unhandled-keywords argument is not supplied, such keywords are complained 
about by signalling an error. But if return-unhandled-keywords is supplied non-nil, a list 
of such keywords is returned as the second value of instantiate -flavor. 

Note that default values in the init-plist can come from the :default-init-plist option to 
defflavor. See page 343. 
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If the send-inil-message-p argument is supplied and non-nil, an :init message is sent to the 
newly-created instance, with one argument, the init-plisi. get can be used to extract 
options from this property-list. Each flavor that needs initialization can contribute an :init 
method by defining a daemon. 

If the area argument is specified, it is the number of an area in which to cons the 
instance; otherwise it is consed in the default area. 

defwrapper Macro 

This is hairy and if you don't understand it you should skip it. 

Sometimes the way the flavor system combines the methods of different flavors (the 
daemon system) is not powerful enough. In that case defwrapper can be used to define a 
macro that expands into code that is wrapped around the invocation of the methods. This 
is best explained by an example; suppose you needed a lock locked during the processing 
of the :foo operation on flavor bar, which takes two arguments, and you have a lock- 
frobboz special-form that knows how to lock the lock (presumably it generates an 
unwind -protect), lock-frobboz needs to see the first argument to the operation; perhaps 
that tells it what sort of operation is going to be performed (read or write), 
(defwrapper (bar :foo) ((argl arg2) . body) 
'(lock-frobboz (self argl) 
. .body)) 
The use of the body macro-argument prevents the defwrapper'ed macro from knowing 
the exact implementation and allows several defwrappers from different flavors to be 
combined properly. 

Note well that the argument variables, argl and arg2, are not referenced with commas 
before them. These may look like defmacro "argument" variables, but they are not. 
Those variables are not bound at the time the defwrapper-defined macro is expanded and 
die back-quoting is done; rather the result of that macro-expansion and back-quoting is 
code which, when a message is sent, will bind those variables to the arguments in the 
message as local variables of the combined method. 

Consider another example. Suppose you thought you wanted a :before daemon, but 
found that if the argument was nil you needed to return from processing the message 
immediately, without executing the primary method. You could write a wrapper such as 
(defwrapper (bar :foo) ((argl) . body) 

'(cond ((null argl)) ;Do nothing if argl is nil 

(t before-code 
• .body))) 

Suppose you need a variable for communication among the daemons for a particular 
operation; perhaps the :after daemons need to know what the primary method diu, anu it 
is something that cannot be easily deduced from just the arguments. You might use an 
instance variable for this, or you might create a special variable which is bound during 
the processing of the operation and used free by the methods. 
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(defvar *communication* ) 
(defwrapper (bar :foo) (ignore . body) 
'(let ( ( *communication* nil)) 
• .body)) 

Similarly you might want a wrapper that puts a *catch around the processing of an 
operation so that any one of the methods could throw out in the event of an unexpected 
condition. 

Like daemon methods, wrappers work in outside-in order; when you add a defwrapper 
to a flavor built on other flavors, the new wrapper is placed outside any wrappers of the 
component flavors. However, all wrappers happen before any daemons happen. When 
the combined method is built, the calls to the beforc-dacmon methods, primary methods, 
and after-daemon methods arc all placed together, and then the wrappers are wrapped 
around them. Thus, if a component flavor defines a wrapper, methods added by new 
flavors will execute within that wrapper's context. 

:around methods can do some of the same tilings that wrappers can. See page 353. If 
one flavor defines both a wrapper and an :around method for the same operation, the 
:around method is executed inside the wrapper. 

By careful about inserting the body into an internal lambda-expression within the 
wrapper's code. This interacts with internals details of the way combined methods are 
implemented. It can be done if it is done carefully. But it is much simpler to use an 
: around method instead. 

undef method {flavor [type] operation [suboperation]) Macro 

(undefmethod (flavor :before :operation)) 
removes the method created by 
(defmethod (flavor :before :operation) (args) ...) 

To remove a wrapper, use undefmethod with :wrapper as the method type. 

undefmethod is simply an interface to fundefine (see page 171) that accepts the same 
syntax as defmethod. 

If a file that used to contain a method definition is reloaded and if that method no longer 
seems to have a definition in the file, the user is asked whether to undefmethod that 
method. This may be important to enable the modified program to inherit the methods it 
is supposed to inherit. If the method in question has been redefined by some other file, 
this is not done, the assumption being that the definition was merely moved. 

self Variable 

When a message is sent to an object, the variable self is automatically bound to that 
object, for the benefit of methods which want to manipulate the object itself (as opposed 
to its instance variables). 
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funcall-self operation arguments... 

When seif is an instance or an entity, (funcaii-seif args...) has the same effect as 
(funcall self args...) except that it is a little faster. If self is not an instance (or an 
entity, see section 11.4. page 185), funcall-self and funcall self do the same thing. 

When self is an instance, funcall-self will only work correctly if it is used in a method 
or a subroutine of a method. Just binding self by hand and using this will not work. 

lexpr-funcall-self operation arguments... list- of- arguments 

This function is a cross between lexpr-funcall and funcall-self. When self is an instance 
or an entity, (lexpr-funcall-self args...) has the same effect as (lexpr-funcall self args...) 
except that it is a little faster. If self is not an instance (or an entity, see section 11.4, 
page 185), lexpr-funcall-self and lexpr-funcall do the same thing. 

funcall-with-mapping-table function mapping-table &rest arguments 

function is applied to arguments with sys:self- mapping -table bound to mapping- table. 
This is faster than binding the variable yourself and doing an ordinary funcall, because 
the system assumes that the mapping table you specify is the correct one for function to 
be run with. However, if you pass the wrong mapping table, incorrect execution will take 
place. 

This function is used in the code for combined methods and is also useful for the user in 
:around methods (see page 353). 

lexpr-funcall-with- mapping-table junction mapping- table test arguments 

junction is applied to arguments using lexpr-funcaii, with sys:seif - mapping -tabie bound 
to mapping- table. 

declare-flavor-instance-variables {flavor) body... Macro 

Sometimes you will write a function which is not itself a method, but which is to be 
called by methods and wants to be able to access the instance variables of the object self. 
The form 

(declare-f lavor- instance- variables {flavor-name) 
(defun Junction args body. . .)) 
surrounds the function definition with a declaration of the instance variables for the 
specified flavor, which will make them accessible by name. Any kind of function 
definition is allowed; it does not have to use defun per se. 

If you call such a function when self's value is an instance whose flavor does not include 
flavor-name as a component, it is an error. 

Cleaner than using declare-flavor-instance-variables, because it does not involve 
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{:se\i -flavor flavorname)) as the first expression in the body of the function. For example: 
(defun foo (a b) 

(declare ( :self-f lavor myobject)) 

(+ a (* b speed))) 
(where speed is an instance variable of the flavor myobject) is equivalent to 
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( dec 1 are-flavor- instance- variables (myobject) 
(defun foo (a b) 
(+ a ( * b speed)) ) ) 

with-self-variables-bound body... Special Form 

Within the body of this special form, all of self's instance variables are bound as specials 
to the values inside self. (Normally this is true only of those instance variables that are 
specified in :special- instance -variables when self's flavor was defined.) 

As a result, inside the body you can use set, boundp and symeval freely on the instance 
variables of self. 

This special form is used by the interpreter when a method that is not compiled is 
executed, so that the interpreted references to instance variables will work properly. 

recompile-f lavor flavor-name &optional single- operation (use- old- combined- methodsX) 
(do- dependents X) 
Updates the internal data of the flavor and any flavors that depend on it. If single- 
operation is supplied non-nil, only the methods for that operation are changed. The 
system does this when you define a new method that did not previously exist. If use-old- 
combined- methods is t, then the existing combined method functions will be used if 
possible. New ones will only be generated if die set of methods to be called has changed. 
This is die default. If use-old-combined-methods is nil, automatically-generated functions to 
call multiple methods or to contain code generated by wrappers will be regenerated 
unconditionally. If do-dependents is nil, only the specific flavor you specified will be 
recompiled. Normally it and all flavors dial depend on it will be recompiled. 

recompile-flavor affects only flavors that have already been compiled. Typically this 
means it affects flavors that have been instantiated, but does not bother with mixins (see 
page 348). 

compile-flavor-methods flavor... Macro 

The form (compile-flavor-methods flavor-name- 1 flavor- name- 2...), placed in a file to be 
compiled, will cause the compiler to include the automatically-generated combined 
methods for the named flavors in the resulting QFASL file, provided all of the necessary 
flavor definitions have been made. Furthermore, when the QFASL file is loaded, internal 
data structures (such as the list of all methods of a flavor) will be generated. 

This means that the combined methods get compiled at compile time and the data 
structures get generated at load time, rather Uian both things happening at run time. This 
is a very good thing, since if the the compiler must be invoked at run time, the program 
will be slow the first time it are run. (The compiler will still be called if incompatible 
changes have been made, such as addition or deletion of methods that must be called by 
a combined method.) 

You should only use compile-flavor-methods for flavors that are going to be 
instantiated. For a flavor that will never be instantiated (that is, a flavor that only serves 
to be a component of other flavors that actually do get instantiated), it is a complete 
waste of time, except in the unusual case where those other flavors can all inherit the 
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method which happens to be identical to the others. In this unusual case, you should use 
the :abstract- flavor option in def flavor. 

The compile-flavor-methods forms should be compiled after all of the information 
needed to create the combined methods is available. You should put these forms after all 
of the definitions of all relevant flavors, wrappers, and methods of all components of the 
flavors mentioned. 

The methods used by compile-flavor-methods to form the combined methods that go in 
the QFASL file arc all those present in the file being compiled and all those defined in 
the Lisp world. 

When a compile-flavor-methods form is seen by the interpreter, the combined methods 
are compiled and the internal data structures are generated. 

get-handler- for object operation 

Given an object and an operation, will return that object's method for that operation, or 
nil if it has none. When object is an instance of a flavor, this function can be useful to 
find which of that flavor's components supplies the method. If you get back a combined 
method, you can use the Meta-X List Combined Methods editor command (page 359) to 
find out what it does. 

This is related to the :handler function spec (see section 10.2, page 154). 



This function can be used with other things than flavors and has an optional argument 
which is not relevant here and not documented. 

flavor-allows- in it-keyword-p flavor-name keyword 

Returns non-nil if the flavor named flavor-name allows keyword in the init options when it 
is instantiated, or nil if it does not. The non-nil value is the name of the component 
flavor that contributes the support of that keyword. 

si :flavor-all-allowed-init-keywords flavor-name 

Returns a list of all the init keywords that may be used in instantiating flavor-name. 

symeval -in- instance instance symbol &optional no-error-p 

This function is used to find the value of an instance variable inside a particular instance. 
Instance is the instance to be examined, and symbol is the instance variable whose value 
should be returned. If there is no such instance variable, an error is signalled, unless no- 
error-p is non-nil in which case nil is returned. 

set-1n-1nstance instance symbol value 

This function is used to alter the value of an instance variable inside a particular instance. 
Instance is the instance to be altered, symbol is the instance variable whose value should 
be set, and value is the new value. If there is no such instance variable, an error is 
signalled. 
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locate-in- instance instance symbol 

Returns a locative pointer to the cell inside instance which holds die value of the instance 
variable named symbol. 

describe -flavor flavor-name 

This function prints out descriptive information about a flavor; it is self-explanatory. An 
important thing it tells you that can be hard to figure out yourself is the combined list of 
component flavors; this list is what is printed after the phrase "and directly or indirectly 
depends on". 

si:*flavor-compilations* Variable 

This variable contains a history of when the flavor mechanism invoked the compiler. It is 
a list; elements toward the front of the list represent more recent compilations. Elements 
are typically of the form 

{function-spec pathname) 
where the function spec starts with :method and has a method type of :combined. 

You may setq this variable to nil at any time; for instance before loading some files that 
you suspect may have missing or obsolete compile -flavor -methods in them. 

sysrunclai me d- message (error) Condition 

This condition is signaled whenever a flavor instance is sent a message whose operation it 
does not handle. The condition instance supports these operations: 

:object The flavor instance that received the message. 

:operation The operation that was not handled. 

:arguments The list of arguments to that operation 

20.8 Defflavor Options 

There are quite a few options to defflavor. They are all described here, although some are 
for very specialized purposes and not of interest to most users. Each option can be written in two 
forms; either the keyword by itself, or a list of the keyword and "arguments" to that keyword. 

Several of these options declare things about instance variables. These options can be given 
with arguments which are instance variables, or without any arguments in which case they refer to 
all of the instance variables listed at the top of the defflavor. This is not necessarily all the 
instance variables of the component flavors, just the ones mentioned in this flavor's defflavor. 
When arguments are given, they must be instance variables that were listed at the top of the 
defflavor; otherwise they are assumed to be misspelled and an error is signalled. It is legal to 
declare things about instance variables inherited from a component flavor, but to do so you must 
list these instance variables explicitly in the instance variable list at the top of the defflavor. 

:gettable - instance - variables 

Enables automatic generation of methods for getting the values of instance variables. The 
operation name is the name of the variable, in the keyword package (i.e. put a colon in 
front of it). 



SRC:<L.MAN>FLAVOR.THXJM01 24-JAN-83 



I Jsp Machine Manual 343 Defflavor Options 



Note that there is nothing special about tliese methods; you could easily define them 
yourself. This option generates them automatically to save you the trouble of writing out 
a lot of very simple method definitions. (The same is true of methods defined by the 
:settable- instance -variables option.) If you define a method for the same operation 
name as one of the automatically generated methods, the new definition will override the 
old one, just as if you had manually defined two methods for the same operation name. 

:settable - instance - variables 

Enables automatic generation of methods for setting the values of instance variables. 'ITie 
operation name is ":set-" followed by the name of the variable. All settable instance 
variables are also automatically made gettable and inittable. (See the note in the 
description of the :gettable- instance -variables option, above.) 

:inittable-instance-variables 

The instance variables listed as arguments, or all instance variables listed in this defflavor 
if the keyword is given alone, are made inittable. This means that they can be initialized 
through use of a keyword (a colon followed by the name of the variable) as an ink-option 
argument to make -instance. 

:special - instance -variables 

The instance variables listed as arguments, or all instance variables listed in this defflavor 
if the keyword is given alone, are made special. Whenever a message is sent to an 
instance of this flavor (or any containing flavor), these instance variables will actually be 
bound as specials: they will be bound through the execution of all the methods. 

You must do this to any instance variables... that .you. wish to be accessible through 

symeval, set, boundp and makunbound. Since those functions refer only to the special 

value cell of a symbol, values of instance variables not made special will not be visible to 
them. 

This should also be done for any instance variables that are declared globally special. If 
you omit this, the flavor system will do it for you automatically when you instantiate the 
flavor, and give you a warning to remind you to fix the defflavor. 

:init-keywords 

The arguments are declared to be valid keywords to use in instantiate -flavor when 
creating an instance of this flavor (or any flavor containing it). The system uses this for 
error-checking: before the system sends the :init message, it makes sure that all the 
keywords in the init-plist are either inittable instance variables or elements of this list. If 
the caller misspells a keyword or otherwise uses a keyword that no component flavor 
handles, this feature will signal an error. When you write a :init method that accepts 
some keywords, they should be listed in the :init- keywords option of the flavor. 

:default-init-plist 

The arguments are alternating keywords and value forms, like a property-list. When the 
flavor is instantiated, these properties and values are put into the init-plist unless already 
present. This allows one component flavor to default an option to another component 
flavor. The value forms are only evaluated when and if they are used. For example, 
( rdefaul t-init-pl ist :frob-array 

(make-array 100)) 
would provide a default "frob array" for any instance for which the user did not provide 
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one explicitly. 

: req u ired - instance - variables 

Declares that any flavor incorporating this one that is instantiated into an object must 
contain the specified instance variables. An error occurs if there is an attempt to 
instantiate a flavor that incorporates this one if it docs not have these in its set of instance 
variables. Note that this option is not one of those that checks the spelling of its 
arguments in the way described at the start of this section (if it did, it would be useless). 

Required instance variables may be freely accessed by methods just like normal instance 
variables. The difference between listing instance variables here and listing them at the 
front of the defflavor is that the latter declares that this flavor "owns" those variables and 
will take care of initializing them, while the former declares that this flavor depends on 
those variables but that some other flavor must be provided to manage them and whatever 
features they imply. 

: required- methods 

The arguments are names of operations that any flavor incorporating this one must handle. 
An error occurs if there is an attempt to instantiate such a flavor and it is lacking a 
method for one of these operations. Typically this option appears in the defflavor for a 
base flavor (sec page 348). Usually this is used when a base flavor does a funcall-self 
(page 339) to send itself a message that is not handled by the base flavor itself; the idea 
is that the base flavor will not be instantiated alone, but only with other components 
(mixins) that do handle the message. This keyword allows the error of having no handler 
for the message be detected when the flavor instantiated or when compile-flavor- 
methods is done, rather than when the missing operation is used. 

: required -flavors 

The arguments are names of flavors that any flavor incorporating this one must include as 
components, directly or indirectly. The difference between declaring flavors as required 
and listing them directly as components at the top of the defflavor is that declaring 
flavors to be required does not make any commitments about where those flavors will 
appear in the ordered list of components; that is left up to whoever does specify them as 
components. The purpose of declaring a flavor to be required is to allow instance 
variables declared by that flavor to be accessed. It also provides error checking: an 
attempt to instantiate a flavor that does not include the required flavors as components 
will signal an error. Compare this with :required- methods and :required-instance- 
variables. 

For an example of the use of required flavors, consider the ship example given earlier, 
and suppose we want to define a relativity- mixin which increases the mass dependent on 
the speed. We might write, 

(defflavor relativi ty-mixin () (moving-object)) 
(defmethod (relativity-mixin :mass) () 

(// mass (sqrt (- 1 (~ (// (funcall-self ' rspeed) 

*speed-of-light*) 

2))))) 

but this would lose because any flavor that had relativity-mixin as a component would get 

moving -object right after it in its component list. As a base flavor, moving -object 

should be last in the list of components so that other components mixed in can replace its 
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business changing the order in which flavors are combined, which should be under the 
control of its caller. For example, 

(defflavor starship {) 

( relativity-mixin long-distance-mixin ship)) 
puts moving -object last (inheriting it from ship). 

So instead of the definition above we write, 

(defflavor relativity-mixin () () 

( :requi red-flavors moving -object) ) 
which allows relativity- mixin's methods to access moving -object instance variables such as 
mass (the rest mass), but does not specify any place for moving -object in the list of 
components. 

It is very common to specify the base flavor of a mixin with the required -flavors option 
in this way. 

included -flavors 

Hie arguments are names of flavors to be included in this flavor. Tlic difference between 
declaring flavors here and declaring them at the top of the defflavor is that when 
component flavors are combined, if an included flavor is not specified as a normal 
component, it is inserted into the list of components immediately after the last component 
to include it. Thus included flavors act like defaults. The important thing is that if an 
included flavor is specified as a component, its position in the list of components is 
completely controlled by that specification, independently of where the flavor that includes 
it appears in the list 

included -flavors and required -flavors are used in similar ways; it would have been 
reasonable to use included -flavors in the relativity-mixin example above. The difference 
is that when a flavor is required but not given as a normal component, an error is 
signalled, but when a flavor is included but not given as a normal component, it is 
automatically inserted into the list of components at a "reasonable" place. 

:no-vanilla-flavor 

Normally when a flavor is instantiated, the special flavor si:vanilla-flavor is included 
automatically at the end of its list of components. The vanilla flavor provides some 
default methods for die standard operations which all objects are supposed to understand. 
These include :print-self, describe, :which -operations, and several other operations. 
See section 20.10, page 348. 

If any component of a flavor specifies the :no-vanilla-flavor option, then si:vanilla-flavor 
will not be included in that flavor. This option should not be used casually. 

:default- handier 

The argument is the name of a function that is to be called when a message is received 
for which there is no method. It will be called with whatever arguments the instance was 
called with, including the operation name; whatever values it returns will be returned. If 
this option is not specified on any component flavor, it defaults to a function that will 
signal an error. 
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:ordered -instance- variables 

This option is mostly for esoteric internal system uses. The arguments are names of 
instance variables which must appear first (and in this order) in all instances of this flavor, 
or any flavor depending on this flavor. This is used for instance variables that are 
specially known about by microcode, and also in connection with the :outside- 
accessible-instance-variables option. If the keyword is given alone, the arguments 
default to die list of instance variables given at the top of this defflavor. 

Removing any of the :ordered- instance -variables, or changing their positions in the list, 
requires that you recompile all methods that use any of the affected instance variables. 

:outside - accessible - instance - variables 

The arguments are instance variables which are to be accessible from "outside" of this 
object, that is from functions other than methods. A macro (actually a defsubst) is 
defined which takes an object of this flavor as an argument and returns the value of the 
instance variable; setf may be used to set the value of the instance variable. The name 
of the macro is the name of the flavor concatenated with a hyphen and the name of the 
instance variable. These macros are similar to the accessor macros created by defstruct 
(see chapter 19, page 298.) 

ITiis feature works in two different ways, depending on whether the instance variable has 
been declared to have a fixed slot in all instances, via the :ordered- instance -variables 
option. 

If the variable is not ordered, the position of its value cell in the instance will have to be 
computed at run time. This takes noticeable time, although less than actually sending a 
message would take. An error will be signalled if the argument to the accessor macro is 
not an instance or is an instance that does not have an instance variable with the 
appropriate name. However, there is no error check that the flavor of the instance is the 
flavor the accessor macro was defined for, or a flavor built upon that flavor. This error 
check would be too expensive. 

If the variable is ordered, the compiler will compile a call to the accessor macro into a 
subprimitive which simply accesses that variable's assigned slot by number. This 
subprimitive is only three or four times slower than car. The only error-checking 
performed is to make sure that the argument is really an instance and is really big enough 
to contain that slot. There is no check that the accessed slot really belongs to an instance 
variable of the appropriate name. 

:accessor- prefix 

Normally the accessor macro created by the :outside-accessible-instance-variables 
option to access the flavor fs instance variable v is named f-v. Specifying (:accessor- 
prefix get$) causes it to be named get$v instead. 

:abstract- flavor 

This option marks the flavor as one that is not supposed to be instantiated (that is, is 
supposed to be used only to make other flavors). An attempt to instantiate the flavor will 
signal an error. 
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It is sometimes useful to do compile -flavor- methods on a flavor that is not going to be 
instantiated, if the combined methods for this flavor will be inherited and shared by many 
others, abstract -flavor tells compile-flavor-methods not to complain about missing 
required flavors, methods or instance variables. Presumably the flavors that depend on 
this one and actually arc instantiated will supply what is lacking. 

:method -combination 

Declares the way that methods from different flavors will be combined. Each "argument" 
to this option is a list {type order operationl operation!...), operation/, operation! , etc. 
are names of operations whose methods are to be combined in the declared fashion, type 
is a keyword that is a defined type of combination; see section 20.11, page 350. Order is 
a keyword whose interpretation is up to type; typically it is either :base- flavor -first or 
:base -flavor- last. 

Any component of a flavor may specify the type of method combination to be used for a 
particular operation. If no component specifies a type of method combination, then the 
default type is used, namely :daemon. If more than one component of a flavor specifies 
it, then they must agree on the specification, or else an error is signalled. 

:documentation 

The list of arguments to this option is remembered on the flavor's property list as the 
documentation property. The (loose) standard for what can be in this list is as follows; 
this may be extended in the future. A string is documentation on what the flavor is for; 
this may consist of a brief overview in the first line, then several paragraphs of detailed 
documentation. A symbol is one of the following keywords: 

:mixin A flavor that you may want to mix with others to provide a useful 

feature. 

-.essential -mixin A flavor that must be mixed in to all flavors of its class, or 
inappropriate behavior will ensue. 

:lowlevel- mixin A mixin used only to build other mixins. 

combination A combination of flavors for a specific purpose. 

:special-purpose A flavor that is not intended for general use, used for some internal 
or kludgey purpose by a particular program. 

This documentation can be viewed with the describe -flavor function (see page 342) or 
the editors Meta-X Describe Flavor command (see page 358). 
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20.9 Flavor Families 

The following organization conventions arc recommended for all programs that use flavors. 

A base flavor is a flavor that defines a whole family of related flavors, all of which will have 
that base flavor as one of their components. Typically the base flavor includes things relevant to 
the whole family, such as instance variables, : required -methods and :required-instance- 
variables declarations, default methods for certain operations, .-method -combination declarations, 
and documentation on the general protocols and conventions of the family. Some base flavors are 
complete and can be instantiated, but most are not instantiatable and merely serve as a base upon 
which to build other flavors. The base flavor for the foo family is often named basic -foo. 

A mixin flavor is a flavor that defines one particular feature of an object. A mixin cannot be 
instantiated, because it is not a complete description. Each module or feature of a program is 
defined as a separate mixin; a usable flavor can be constructed by choosing the mixins for the 
desired characteristics and combining them, along with the appropriate base flavor. By organizing 
your flavors this way, you keep separate features in separate flavors, and you can pick and choose 
among them. Sometimes the order of combining mixins docs not matter, but often it does, 
because the order of flavor combination controls the order in which daemons are invoked and 
wrappers are wrapped. Such order dependencies should be documented as part of the conventions 
of the appropriate family of flavors. A mixin flavor that provides the mumble feature is often 
named mumble- mixin. 

If you are writing a program that uses someone else's facility to do something, using that 
facility's flavors and methods, your program may still define its own flavors, in a simple way. 
The facility provides a base flavor and a set of mixins: the caller can combine these in various 
ways depending on exactly what it wants, since the facility probably will not provide all possible 
useful combinations. Even if your private flavor has exactly the same components as a pre- 
existing flavor, it can still be useful since you can use its :default-init-plist (see page 343) to 
select options of its component flavors and you can define one or two methods to customize it 
"just a little". 

20.10 Vanilla Flavor 

The operations described in this section are a standard protocol, which all message-receiving 
objects are assumed to understand. The standard methods that implement this protocol are 
automatically supplied by the flavor system unless the user specifically tells it not to do so. These 
methods are associated with the flavor si:vani!la-flavor: 

si: vanilla-flavor Flavor 

Unless you specify otherwise (with the :no-vanilla-flavor option to defflavor), every 

flavor includes the "vanilla" flavor, which has no instance variables but provides some 
basic useful methods. 
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print-self stream prindepth slashify-p Operation 

The object should output its printed-representation to a stream. The printer sends this 
message when it encounters an instance or an entity. The arguments are the stream, the 
current depth in list-structure (for comparison with prinlevel), and whether slashification is 
enabled (prinl vs pnnc", see page 36/). van'ma-flavor ignores tnc last two arguments anu 
prints something like #< flavor- name octal- address>. The flavor-name tells you what type 
of object it is and the octal-address allows you to tell different objects apart (provided the 
garbage collector doesn't move them behind your back). 

; describe Operation 

The object should describe itself, printing a description onto the standard -output stream. 
The describe function sends this message when it encounters an instance or an entity. 
Vanilla-flavor outputs in a reasonable format the object, the name of its flavor, and the 
names and values of its instance-variables. 

:which-operations Operation 

The object should return a list of the operations it can handle. Vanilla-flavor generates 
the list once per flavor and remembers it. minimizing consing and compute-time. If a 
new method is added, the list is regenerated the next time someone asks for it. 

:operation-handled-p operation Operation 

operation is an operation name. The object should return t if it has a handler for the 
specified operation, nil if it does not. 

:get-handler-for operation Operation 

operation is an operation name. Ilie object should return the method it uses to handle 
operation. If it has no handler for that operation, it should return nil. This is like the 
get-handler-for function (see page 341), but, of course, you can use it only on objects 
known to accept messages. 

:send-if-handles operation test arguments Operation 

operation is an operation name and arguments is a list of arguments for the operation. If 
the object handles the operation, it should send itself a message with that operation and 
arguments. If it doesn't handle the operation it should just return nil. 

:eval-inside-yourself form Operation 

The argument is a form that is evaluated in an environment in which special variables 
with the names of the instance variables are bound to the values of the instance variables. 
It works to setq one of these special variables; the instance variable will be modified. 
This is intended to be used mainly for debugging. 

:funca11-inside-yourself junction test args Operation 

junction is applied to args in an environment in which special variables with the names Oi 
the instance variables are bound to the values of the instance variables. It works to setq 
one of these special variables; the instance variable will be modified. This is a way of 
allowing callers to provide actions to be performed in an environment set up by the 
instance. 
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: break Operation 

break is called in an environment in which special variables with the names of the 
instance variables are bound to the values of the instance variables. 



20.11 Method Combination 

As was mentioned earlier, there are many ways to combine methods. The way we have seen 
is called the :daemon type of combination. To use one of the others, you use the :method- 
combination option to defflavor (sec page 347) to say that all the methods for a certain operation 
on this flavor, or any flavor built on it, should be combined in a certain way. 

The following types of method combination are supplied by the system. It is possible to 
define your own types of method combination; for information on this, see the code. Note that 
for most types of method combination other than :daemon you must define the order in which 
the methods are combined, cither :base-flavor-first or :base- flavor -last, in the :method- 
combination option. In this context, "base-flavor" means the last element of the flavor's fully- 
expanded list of components. 

A few method types (:default, :around) have a universal meaning independent of the method 
combination type. Aside from these, the method type keywords allowed vary depending on the 
type of method combination selected, and many combination types allow only untyped methods. 
There are also certain method types used for internal purposes. 

:daemon This is the default type of method combination. All the :before methods are 

called, then the primary (untyped) method for the outermost flavor that has one is 
called, then all the :after methods are called. The value returned is the value of 
the primary method. 

:daemon-with-or 

This is like the :daemon method combination type, except that the primary 
method is wrapped in an :or special form with all :or methods. Multiple values 
will be returned from the primary method, but not from the :or methods. This 
will produce combined methods like this (simplified to ignore multiple values): 

(progn (foo-before-method) 
(or (foo-or-method) 

(f oo- primary-method)) 
(f oo- after -method) ) 

This is useful primarily for flavors in which a mixin introduces an alternative to 
the primary method. Each :or method gets a chance to run before the primary 
method and to decide whether the primary method should be run or not; if any 
:or method returns a non-nil value, the primary method is not run (nor are the 
rest of the :or methods). Note that the ordering of the combination of the :or 
methods is controlled by the order keyword in the :method -combination option 
to defflavor (see page 347). 

:daemon -with -and 

This is like :daemon-with-or except that it combines :and methods in an and 
special form. The primary method will only be run if all of the :and methods 
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return non-nil values. 

:daemon -with -override 

This is like the :daemon method combination type, except an or special form is 
wrapped around the entire combined method with all :override typed methods 
before the combined method. This differs from :daemon-with-or in that the 
:before and :after daemons are run only if none of the :override methods returns 
non-nil. The combined method looks something like this: 

(or (foo-override-method) 

(progn (foo-bef ore-method) 
(f oo- primary-met hod) 
(foo-af ter-method) ) ) 

All the methods are called, inside a progn special form. No typed methods are 
allowed. The result of the combined method is whatever the last of the methods 
returns. 



:progn 



:or 



:and 

:append 

:nconc 

:list 

:inverse-list 



:pass-on 



All the methods are called, inside an or special form. No typed methods are 
allowed. This means that each of the methods is called in turn. If a method 
returns a non-nil value, that value is returned and none of the rest of the 
methods arc called; otherwise, the next method is called. In other words, each 
method is given a chance to handle the message; if it doesn't want to handle the 
message, it should return nil, and the next method will get a chance to try. 

All the methods are called, inside an and special form. No typed methods are 
allowed. The basic idea is much like :or; see above. 

All the mediods are called, and the values are appended together. 

All the methods are called, and the values are neone'd together. 

Calls all the methods and returns a list of their returned values. No typed 
methods are allowed. 

Calls each method with one argument; these arguments are successive elements of 
the list that is the sole argument to the operation. No typed methods are allowed. 
Returns no particular value. If the result of a :list-combined operation is sent 
back with an :inverse -list-combined operation, with the same ordering and with 
corresponding method definitions, each component flavor receives the value that 
came from that flavor. 

Calls each method on the values returned by the preceeding one. The values 
returned by the combined method are those of the outermost call. The format of 
the declaration in the defflavor is: 



(: method-combination (: pass-on (ordering 

. operation- names) 



arelist\ ) 



:case 



Where ordering is :base-flavor-first or :base- flavor -last, arglist may include the 
&aux and &optional keywords. 

With :case method combination, the combined method automatically does a 
selectq dispatch on the first argument of the operation, known as the 
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subopcration. Methods of type :case can be used, and each one specifics one 
subopcration that it applies to. If no :case method matches the subopcration, the 
primary method, if any, is called. 

Example: 

(defflavor foo (a b) ( ) 

( :method-combination (:case :base-f lavor-last :win))) 

This method will handle (send a-foo ':win ':a): 

(defmethod (foo :case :win :a) () 
a) 

This method will handle (send a-foo ':win ':a*b): 

(defmethod (foo :case :win :a*b) () 
(• a *>)) 

This method will handle (send a-foo ':win ':something-else): 
(defmethod (foo :win) ( suboperation) 
(list 'something-random suboperation)) 

:case metliods are unusual in that one flavor can have many :case methods for 
the same operation, as long as they arc for different suboperations. 

The suboperations :which- operations, :operation- handled -p, :send- if- handles 
and :get- handler -for are all handled automatically based on the collection of 
:case methods that are present 

Methods of type :or are also allowed. They are called just before the primary 
method, and if one of them returns a non-nil value, that is the value of the 
operation, and no more methods are called. 

Here is a table of all the method types used in the standard system. A user can add more, 
by defining new forms of method-combination. 



(no type) 

:before 
:after 

:default 



If no type is given to defmethod, a primary method is created. This is the most 
common type of method. 

These are used for the before-daemon and after-daemon methods used by 
:daemon method-combination. 

If there are no untyped methods among any of the flavors being combined, then 
the :default methods (if any) arc treated as if they were untyped. If there are any 
untyped methods, the :default methods are ignored. 

Typically a base-flavor (see page 348) will define some default methods for certain 
of the operations understood by its family. When using the default kind of 
method-combination these default methods will not be called if a flavor provides 
its own method. But with certain strange forms of method-combination (:or for 
example) the base-flavor uses a :default method to achieve its desired effect. 
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:or 

:and These are used for :daemon-with-or and :daemon -with -and method 

combination. The :or methods arc wrapped in an or, or the :and methods are 
wrapped in an and, together with the primary method, between the :before and 
:after methods. 

override This allows the features of :or method-combination to be used together with 

daemons. If you specify method-combination type :daemon- with -override, you 
may use :override methods. The :override methods arc executed first, until one 
of them returns non-nil. If this happens, that method's value(s) are returned and 
no more methods are used. If all the .override mcdiods return nil, the :before, 
primary and :after methods are executed as usual. 

In typical usages of this feature, the :override method usually returns nil and does 
nothing, but in exceptional circumstances it takes over the handling of the 
operation. 

:case :case methods are used by :case method combination. 

These method types can be used with any method combination type; they have standard meanings 
independent of the method combination type being used. 

:around An :around method is able to control when, whether and how die remaining 

methods will be executed. It is given a continuation that is a function that will 
execute the remaining methods, and has complete responsibility for calling it or 
not, and deciding what arguments to give it. For the simplest behavior, the 
arguments should be me operation name and upcialiuu arguments that the 
:around method itself received; but sometimes the whole purpose of the :around 
method is to modify the arguments before the remaining methods see them. 

The :around method receives three special arguments before the arguments of the 
operation itself: the continuation, the mapping- table, and the original- argument- 
list. The last is a list of the operation name and operation arguments. The 
simplest way for the :around method to invoke the remaining methods is to do 
(lexpr-funcall -with -mapping- table 

continuation mapping- table 

original- argument-list ) 
In general, the continuation should be called with either funcall -with- mapping - 
table or lexpr-funcall -with -mapping -table, providing the continuation, the 
mapping- table, and the operation name (which you know because it is the same as 
in the defmethod), followed by whatever arguments the remaining methods are 
supposed to see. 

(def flavor foo-one-bigger-mixin () (;/ 

(defmethod (foo-one-bigger-mixin :around :set-foo) 
(cont mt ignore new-foo) 
(funcall-with-mapping-table cont mt ':set-foo 

( 1+ new-foo)) ) 
is a mixin which modifies the :set-foo operation so that the value actually used in 
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it is one greater than the value specified in the message, 
wrapper This type is used internally by defwrapper. 

Note that if one flavor defines both a wrapper and an :around method for the 
same operation, the :around method is executed inside the wrapper. 

combined Used internally for automatically-generated combined methods. 

The most common form of combination is :daemon. One thing may not be clear: when do 
you use a :before daemon and when do you use an :after daemon? In some cases the primary 
method performs a clearly-defined action and the choice is obvious: :before :launch- rocket puts 
in the fuel, and :after : launch -rocket turns on the radar tracking. 

In other cases the choice can be less obvious. Consider the :init message, which is sent to a 
newly-created object. To decide what kind of daemon to use, we observe the order in which 
daemon methods are called. First the :before daemon of the highest level of abstraction is called, 
then :before daemons of successively lower levels of abstraction are called, and finally the :before 
daemon (if any) of the base flavor is called. ITien the primary method is called. After that, the 
:after daemon for the lowest level of abstraction is called, followed by the :after daemons at 
successively higher levels of abstraction. 

Now, if there is no interaction among all these methods, if their actions are completely 
orthogonal, then it doesn't matter whether you use a :before daemon or an :after daemon. It 
makes a difference if there is some interaction. The interaction we are talking about is usually 
done through instance variables; in general, instance variables are how the methods of different 
component flavors communicate with each other. In the case of the :init operation, the init-plist 
can be used as well. r Ifie important thing to remember is diat no method knows beforehand 
which other flavors have been mixed in to form this flavor; a method cannot make any 
assumptions about how this flavor has been combined, and in what order the various components 
are mixed. 

This means that when a :before daemon has run, it must assume that none of the methods 
for this operation have run yet. But the :after daemon knows that the :before daemon for each 
of the other flavors has run. So if one flavor wants to convey information to the other, the first 
one should "transmit" the information in a :before daemon, and the second one should "receive" 
it in an :after daemon. So while the :before daemons are am, information is "transmitted"; that 
is, instance variables get set up. Then, when the :after daemons are run, they can look at the 
instance variables and act on their values. 

In the case of the :init method, the :before daemons typically set up instance variables of the 
object based on the init-plist, while die :after daemons actually do things, relying on the fact that 
all of the instance variables have been initialized by the time they are called. 

The problems become most difficult when you are creating a network of instances of various 
flavors that are supposed to point to each other. For example, suppose you have flavors for 
"buffers" and "streams", and each buffer should be accompanied by a stream. If you create the 
stream in the :before :init method for buffers, you can inform the stream of its corresponding 
buffer with an init keyword, but the stream may try sending messages back to the buffer, which 
is not yet ready to be used. If you create the stream in the :after :init method for buffers, there 
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will be no problem with stream creation, but some other :after :init methods of other mixins may 
have run and made the assumption that there is to be no stream. The only way to guarantee 
success is to create the stream in a :before method and inform it of its associated buffer by 
sending it a message from the buffer's :after :init method. This scheme— creating associated 
objects in :before methods but linking them up in :after methods — often avoids problems, 
because all the various associated objects used by various mixins will at least exist before anything 
is done with any of them. 

Of course, since flavors arc not hierarchically organized, the notion of levels of abstraction is 
not strictly applicable. However, it remains a useful way of thinking about systems. 

20.12 Implementation of Flavors 

An object that is an instance of a flavor is implemented using the data type dtp -instance. 
The representation is a structure whose first word, tagged with dtp -instance -header, points to a 
structure (known to the microcode as an "instance descriptor") containing the internal data for the 
flavor. The remaining words of the structure are value cells containing the values of the instance 
variables. The instance descriptor is a defstruct that appears on the skflavor property of the 
flavor name. It contains, among other things, the name of the flavor, the size of an instance, the 
table of methods for handling operations, and information for accessing the instance variables. 

defflavor creates such a data structure for each flavor, and links them together according to 
the dependency relationships between flavors. 

A message is 'sent to "an instance simpiy by calling ii as a funutiun, willi Hie fii'st argument 
being the operation. The microcode binds self to the object and binds those instance variables 
that are defined to be special to die value cells in the instance. Then it passes on the operation 
and arguments to a funcallable hash table taken from the flavor-structure for this flavor. 

When the funcallable hash table is called as a function, it hashes the first argument (the 
operation) to find a function to handle the operation and an array called a mapping table. The 
variable sys:self- mapping -table is bound to the mapping table, which tells the microcode how 
to access the other instance variables, those not defined to be special. Then the function is called. 
If there is only one method to be invoked, this function is that method; otherwise it is an 
automatically-generated function called the combined method (see page 332), which calls the 
appropriate methods in die right order. If there are wrappers, they are incorporated into this 
combined method. 

The mapping table is an array whose elements correspond to the instance variables which can 
be accessed by the flavor to which the currently executing method belongs. Each element contains 
the position in self of that instance variable. This position varies with the other instance variables 
and component flavors of the flavor of self. 

Each time the combined method calls another method, it sets up the mapping table required 
by that method— not in general the same one which the combined method itself uses. The 
mapping tables for the called methods are extracted from the array leader of the mapping table 
used by the combined method, which is kept in a local variable of the combined method's stack 
frame while sys:self- mapping -table is set to the mapping tables for the component methods. 
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sys: self -mapping-table Variable 

This variable holds the current mapping table, which tells the running flavor method 
where in self to find each instance variable. 

Ordered instance variables are referred to directly without going through the mapping table. 
This is a little faster, and reduces the amount of space needed for mapping tables. It is also the 
reason why compiled code contains the positions of the ordered instance variables and must be 
recompiled when they change. 

20.12.1 Order of Definition 

There is a certain amount of freedom to the order in which you do defflavor's, defmethod's, 
and defwrapper's. This freedom is designed to make it easy to load programs containing complex 
flavor structures without having to do things in a certain order. It is considered important that 
not all the methods for a flavor need be defined in the same file. Thus the partitioning of a 
program into files can be along modular lines. 

The rules for the order of definition are as follows. 

Before a method can be defined (with defmethod or defwrapper) its flavor must have been 
defined (with defflavor). This makes sense because the system has to have a place to remember 
the method, and because it has to know the instance-variables of the flavor if the method is to be 
compiled. 

When a flavor is defined (with defflavor) it is not necessary that all of its component flavors 
be defined already. This is to allow defflavor's to be spread between files according to the 
modularity of a program, and to provide for mutually-dependent flavors. Methods can be defined 
for a flavor some of whose component flavors are not yet defined; however, in certain cases 
compiling those methods will produce a warning that an instance variable was declared special 
(because the system did not realize it was an instance variable). If this happens, you should fix 
the problem and recompile. 

The methods automatically generated by the :gettable- instance -variables and :settable- 
instance-variables defflavor options (see page 342) are generated at the time the defflavor is 
done. 

The first time a flavor is instantiated, or when compile -flavor- methods is done, the system 
looks through all of the component flavors and gathers various information. At this point an error 
will be signalled if not all of the components have been defflavor'ed. This is also the time at 
which certain other errors are detected, for instance lack of a required instance-variable (see the 
:required-instance-variables defflavor option, page 344). The combined methods (see page 332) 
are generated at this time also, unless they already exist. 

After a flavor has been instantiated, it is possible to make changes to it. These changes will 
affect all existing instances if possible. This is described more fully immediately below. 
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20.12.2 Changing a Flavor 

You can change anything about a flavor at any time. You can change the flavor's general 
attributes by doing another def flavor with the same name. You can add or modify methods by 
doing def method's. If you do a def method with the same flavor-name, operation (and 
suboperation if any), and (optional) method-type as an existing method, that method is replaced 
by the new definition. You can remove a method with undefmethod (see page 338). 

ITicse changes will always propagate to all flavors that depend upon the changed flavor. 
Normally the system will propagate the changes to all existing instances of the changed flavor and 
all flavors that depend on it. However, this is not possible when the flavor has been changed so 
drastically that the old instances would not work properly with the new flavor. This happens if 
you change the number of instance variables, which changes the size of an instance. It also 
happens if you change the order of the instance variables (and hence the storage layout of an 
instance), or if you change die component flavors (which can change several subtle aspects of an 
instance). The system does not keep a list of all the instances of each flavor, so it cannot find 
the instances and modify them to conform to the new flavor definition. Instead it gives you a 
warning message, on the error -output stream, to the effect that the flavor was changed 
incompatibly and the old instances will not get the new version. The system leaves the old flavor 
data-structure intact (the old instances will continue to point at it) and makes a new one to 
contain the new version of the flavor. If a less drastic change is made, the system modifies the 
original flavor data-structure, thus affecting the old instances that point at it. However, if you 
redefine methods in such a way that they only work for the new version of the flavor, then trying 
to use those methods with the old instances won't work. 

20.12.3 Restrictions 

There is presendy an implementation restriction that when using daemons, the primary 
method may return at most three values if diere are any :after daemons. This is because the 
combined method needs a place to remember the values while it calls the daemons. This will be 
fixed some day. 

20.13 Entities 

An entity is a Lisp object; the entity is one of the primitive datatypes provided by the Lisp 
Machine system (the data-type function (see page 201) will return dtp-entity if it is given an 
entity). Entities are just like closures: they have all the same attributes and functionality. The 
only difference between the two primitive types is their data type: entities are clearly 
distinguished from closures because they have a different data type. The reason there is an 
important difference between them is that various parts of the (not so primitive) Lisp system treat 
Aom HiffVwntiv Thp I .ten functions that deal with entities are discussed in section 11.4, page 

185. 

A closure is simply a kind of function, but an entity is assumed to be a message- receiving 
object. Thus, when the Lisp printer (see section 21.2.1, page 367) is given a closure, it prints a 
simple textual representation, but when it is handed an entity, it sends the entity a :print-self 
message, which the entity is expected to handle. The describe function (see page 641) also sends 
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entities messages when it is handed them. So when you want to make a message-receiving object 
out of a closure, as described on page 327, you should use an entity instead. 

Usually there is no point in using entities instead of flavors. Flavors have had considerably 
more attention paid to their efficiency and to good tools for using them. If what you are doing is 
flavor-like, it is better to use flavors. 

Entities are created with die entity function (see page 185). The function part of an entity 
should usually be a function created by defselect (see page 167). 

20.14 Useful Editor Commands 

Since we presently lack an editor manual, this section briefly documents some editor 
commands that are useful in conjunction with flavors. 

Meta-. 

The Meta-. (Edit Definition) command can find the definition of a flavor in the same 
way that it can find the definition of a function. 

Edit Definition can find the definition of a method if you it a suitable function spec 
starting with :method. The keyword :method may be omitted if the definition is in the 
editor already. Completion will occur on the flavor name and operation name as usual. 

Meta-X Describe Flavor 

Asks for a flavor name in the mini-buffer and describes its characteristics. When typing 
the flavor name you have completion over the names of all defined flavors (thus this 
command can be used to aid in guessing the name of a flavor). The display produced is 
mouse sensitive where there are names of flavors and of methods; as usual die right-hand 
mouse button gives you a menu of operations and the left-hand mouse button does the 
most common operation, typically positioning the editor to the source code for the thing 
you are pointing at. 

Meta-X List Methods 

Meta-X Edit Methods 

Asks you for an operation in the mini-buffer and lists all the flavors that have a method 
for that operation. You may type in the operation name, point to it with the mouse, or 
let it default to the operation of the message being sent by the Lisp form the cursor is 
on. List Methods produces a mouse-sensitive display allowing you to edit selected 
methods or just to see which flavors have methods, while Edit Methods skips the display 
and proceeds directly to editing the methods. 

As usual with this type of command, the editor command Control -Shift-P will advance 
the editor cursor to the next method in the list, reading in its source file if necessary. 
Typing Control -Shift-P, while the display is on the screen, edits the first method. 

In addition, you can find a copy of the list in the editor buffer * Possibilities*. While in 
that buffer, the command Control-/ will visit the definition of die method described on 
the line the cursor is pointing at. 
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These techniques of moving through the objects listed apply to all the following 
commands as well. 

Meta-X List Combined Methods 

Meta-X Edit Combined Methods 

Asks you for an operation name and a flavor in two mini-buffers and lists all the methods 
that would be called to handle that operation for an instance of that flavor. 

List Combined Methods can be very useful for telling what a flavor will do in response 
to a message. It shows you the primary method, the daemons, and die wrappers and lets 
you see the code for all of them; type Control-Shift-P to get to successive ones. 

Meta-X List Flavor Components 
Meta-X Edit Flavor Components 

Asks you for a flavor and lists or begins visiting all the flavors it depends on. 

Meta-X List Flavor Dependents 
Meta-X Edit Flavor Dependents 

Asks you for a flavor and lists or begins visiting all the flavors which depend on it. 

Meta-X List Flavor Direct Dependents 
Meta-X Edit Flavor Direct Dependents 

Asks you for a flavor and lists or begins visiting all the flavors which depend on it. 

Meta-X List Flavor Methods 
Meta-X Edit Flavor Methods 

Asks you for a flavor and lists or begins visiting all the methods defined for that flavor. 
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20.15 Property List Operations 

It is often useful to associate a property list with an abstract object, for the same reasons that 
it is useful to have a property list associated with a symbol. This section describes a mixin flavor 
that can be used as a component of any new flavor in order to provide that new flavor with a 
property list. For more details and examples, see the general discussion of property lists (section 
5.9, page 81). The usual property list functions (get, putprop, etc.) all work on instances by 
sending the instance the corresponding message. 

si:property-Hst-m1x1n Flavor 

This mixin flavor provides the basic operations on property lists. 

:get property-name Operation on s\:proper\y-\\s\-n)\x\n 

The :get operation looks up the object's property- name property. If it finds such a 
property, it returns the value; otherwise it returns nil. 

:get! property- name- list Operation on si: property -list -mixin 

The :getl operation is like the :get operation, except that the argument is a list of 
property names. The :getl operation searches down the property list until it finds a 
property whose property name is one of the elements of property-name-list. It returns the 
portion of the property list begining with the first such property that it found. If it 
doesn't find any, it returns nil. 
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:putprop value property-name Operation of/si:property-list-mixin 

lliis gives the object an property-name property of value. 

: remp rop property-name Operation un si:property- list-mixin 

This removes the object's property-name property, by splicing it out of the property list. 
It returns one of the cells spliced out, whose car is the former value of the property that 
was just removed. If there was no such property to begin with, the value is nil. 

: get-location property-name Operation o/z si: property -list-mixin 

Returns a locative pointer to the cell in which this object's property- name property is 
stored. If there is no such property, a cell is added to the property list and initialized to 
nil, and a pointer to that cell is returned. This operation never returns nil. 

: push-property value property-name Operation on s\:property- list-mixin 

The property-name property of the object should be a list (note that nil is a list and an 
absent property is nil). This operation sets the property-name property of the object to a 
list whose car is value and whose cdr is the former property-name property of the list. 
This is analogous to doing 

(push value (get object property- name)) 
See the push special form (page 272). 

:property-!1st Operation on si: property -list-mixin 

This returns the list of alternating property names and values that implements the property 
list 

: property- list-location Operation on s\:proper\y- list-mixin 

This returns a locative pointer to the cell in the instance which holds the property list 
data. 

:set-property-Hst list Operation on sv.property- list-mixin 

This sets the list of alternating property names and values that implements the property 
list to list. 

: property-list list (Init option fors\:property-\\st-tr\\xm) 

This initializes the list of alternating property names and values that implements the 
property list to list. 

20.16 Printing Flavor Instances Readably 

A flavor instance can print out so that it can be read back in, as long as you give it a rprint- 
self method that produces a suitable printed representation, and provide a way to parse it. The 
convention for doing this is to print as 
ffeflavor-name additional- daico 
and make sure that the flavor defines or inherits a :read- instance method that can parse the 
additional- data and return an instance (see page 377). A convenient way of doing this is to use 
skprint-readably-mixin. 
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si :print-readably-mixin Flavor 

This mixin provides for flavor instances to print out using the #c syntax, and also for 
reading tilings that were printed in that way. 

: reconstruction- in it-pl ist Operation o//si:print-rsadab!y-rnixin 

When you use si:print-readably-mixin. you must define the operation :reconstruction- 
init-plist. 'ITiis should return an alternating list of init options and values that could be 
passed to make -instance to create an instance "like" this one. 
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